~ chicken-core (chicken-5) /manual/Module (chicken memory representation)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken memory representation)56The procedures from this module operate on the in-memory7representation of Scheme objects. These procedures ''are'' safe, so,8for example, unlike the procedures from {{(chicken memory)}} these9procedures ''will'' type-check and range-check their arguments, but10you still need to know what you're doing because the effects may be11surprising for the uninitiated.121314=== Extending procedures with data151617==== extend-procedure1819<procedure>(extend-procedure PROCEDURE X)</procedure>2021Returns a copy of the procedure {{PROCEDURE}} which contains an22additional data slot initialized to {{X}}. If {{PROCEDURE}} is already23an extended procedure, then its data slot is changed to contain {{X}}24and the same procedure is returned. Signals an error when25{{PROCEDURE}} is not a procedure.262728==== extended-procedure?2930<procedure>(extended-procedure? PROCEDURE)</procedure>3132Returns {{#t}} if {{PROCEDURE}} is an extended procedure,33or {{#f}} otherwise.343536==== procedure-data3738<procedure>(procedure-data PROCEDURE)</procedure>3940Returns the data object contained in the extended procedure41{{PROCEDURE}}, or {{#f}} if it is not an extended procedure.424344==== set-procedure-data!4546<procedure>(set-procedure-data! PROCEDURE X)</procedure>4748Changes the data object contained in the extended procedure49{{PROCEDURE}} to {{X}}. Signals an error when {{PROCEDURE}} is not an50extended procedure.5152<enscript highlight=scheme>53(define foo54 (letrec ((f (lambda () (procedure-data x)))55 (x #f) )56 (set! x (extend-procedure f 123))57 x) )58(foo) ==> 12359(set-procedure-data! foo 'hello)60(foo) ==> hello61</enscript>62636465=== Low-level data access6667These procedures operate with what are known as ''vector-like68objects''. A ''vector-like object'' is a vector, record structure,69pair, symbol or keyword: it is an aggregation of other Scheme objects.7071Note that strings and blobs are not considered vector-like (they are72considered to be ''byte vectors'', which are objects of mostly73unstructured binary data).747576==== vector-like?7778<procedure>(vector-like? X)</procedure>7980Returns {{#t}} when {{X}} is a vector-like object, returns {{#f}}81otherwise.828384==== block-ref8586<procedure>(block-ref VECTOR* INDEX)</procedure>8788Returns the contents of the {{INDEX}}th slot of the vector-like object89{{VECTOR*}}.909192==== block-set!9394<procedure>(block-set! VECTOR* INDEX X)</procedure><br>95<procedure>(set! (block-ref VECTOR* INDEX) X)</procedure>9697Sets the contents of the {{INDEX}}th slot of the vector-like object98{{VECTOR*}} to the value of {{X}}.99100==== number-of-slots101102<procedure>(number-of-slots VECTOR*)</procedure>103104Returns the number of slots that the vector-like object {{VECTOR*}}105contains.106107108==== number-of-bytes109110<procedure>(number-of-bytes BLOCK)</procedure>111112Returns the number of bytes that the object {{BLOCK}}113contains. {{BLOCK}} may be any non-immediate value.114115116==== object-copy117118<procedure>(object-copy X)</procedure>119120Copies {{X}} recursively and returns the fresh copy. Objects allocated121in static memory are copied back into garbage collected storage.122123124=== Record instance125126127==== make-record-instance128129<procedure>(make-record-instance SYMBOL ARG1 ...)</procedure>130131Returns a new instance of the record type {{SYMBOL}}, with its132slots initialized to {{ARG1 ...}}. To illustrate:133134<enscript highlight=scheme>135(define-record-type point (make-point x y) point?136 (x point-x point-x-set!)137 (y point-y point-y-set!))138</enscript>139140expands into something quite similar to:141142<enscript highlight=scheme>143(begin144 (define (make-point x y)145 (make-record-instance 'point x y) )146 (define (point? x)147 (and (record-instance? x)148 (eq? 'point (block-ref x 0)) ) )149 (define (point-x p) (block-ref p 1))150 (define (point-x-set! p x) (block-set! p 1 x))151 (define (point-y p) (block-ref p 2))152 (define (point-y-set! p y) (block-set! p 1 y)) )153</enscript>154155156==== record-instance?157158<procedure>(record-instance? X [SYMBOL])</procedure>159160Returns {{#t}} if {{X}} is a record structure, or {{#f}} otherwise.161162Further, returns {{#t}} if {{X}} is of type {{SYMBOL}}, or {{#f}}163otherwise.164165166==== record-instance-type167168<procedure>(record-instance-type RECORD)</procedure>169170Returns type symbol of the record structure {{RECORD}}. Signals an171error if {{RECORD}} is not a record structure.172173174==== record-instance-length175176<procedure>(record-instance-length RECORD)</procedure>177178Returns number of slots for the record structure {{RECORD}}. The179record-instance type is not counted. Signals an error if180{{RECORD}} is not a record structure.181182183==== record-instance-slot184185<procedure>(record-instance-slot RECORD INDEX)</procedure>186187Returns the contents of the {{INDEX}}th slot of the record structure188{{RECORD}}. The slot index range is the open interval {{[0189record-instance-length)}}. Signals an error if {{RECORD}} is not a record190structure.191192193==== record-instance-slot-set!194195<procedure>(record-instance-slot-set! RECORD INDEX X)</procedure><br>196<procedure>(set! (record-instance-slot RECORD INDEX) X)</procedure>197198Sets the {{INDEX}}th slot of the record structure {{RECORD}} to199{{X}}. The slot index range is the open interval {{[0200record-instance-length)}}. Signals an error if {{RECORD}} is not a201record structure.202203204==== record->vector205206<procedure>(record->vector RECORD)</procedure>207208Returns a new vector with the type and the elements of the record209structure {{RECORD}}. Signals an error if {{RECORD}} is not a record210structure.211212213=== Magic214215216==== object-become!217218<procedure>(object-become! ALIST)</procedure>219220Changes the identity of the value of the car of each pair in {{ALIST}}221to the value of the cdr. Neither value may be immediate (i.e. exact222integers, characters, booleans or the empty list).223224<enscript highlight=scheme>225(define x "i used to be a string")226(define y '#(and now i am a vector))227(object-become! (list (cons x y)))228x ==> #(and now i am a vector)229y ==> #(and now i am a vector)230(eq? x y) ==> #t231</enscript>232233Note: this operation invokes a major garbage collection.234235The effect of using {{object-become!}} on evicted data (see236{{object-evict}}) is undefined.237238239==== mutate-procedure!240241<procedure>(mutate-procedure! OLD PROC)</procedure>242243Replaces the procedure {{OLD}} with the result of calling the244one-argument procedure {{PROC}}. {{PROC}} will receive a copy of245{{OLD}} that will be identical in behaviour to the result of {{OLD}}:246247<enscript highlight=scheme>248 ;;; Replace arbitrary procedure with tracing one:249250 (mutate-procedure! my-proc251 (lambda (new)252 (lambda args253 (printf "~s called with arguments: ~s~%" new args)254 (apply new args) ) ) )255</enscript>256257258---259Previous: [[Module (chicken memory)]]260261Next: [[Module (chicken module)]]